android.ndk.surface_texture source code

1 /*
2  * Copyright (C) 2018 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /**
18  * @addtogroup SurfaceTexture
19  * @{
20  */
21 
22 /**
23  * @file surface_texture.h
24  */
25 
26 module android.ndk.surface_texture;
27 
28 import arsd.jni;
29 import android.ndk;
30 
31 extern (C):
32 nothrow:
33 @nogc:
34 
35 /******************************************************************
36  *
37  * IMPORTANT NOTICE:
38  *
39  *   This file is part of Android's set of stable system headers
40  *   exposed by the Android NDK (Native Development Kit).
41  *
42  *   Third-party source AND binary code relies on the definitions
43  *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
44  *
45  *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
46  *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
47  *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
48  *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
49  */
50 
51 struct ASurfaceTexture;
52 
53 /**
54  * {@link ASurfaceTexture} is an opaque type to manage SurfaceTexture from native code
55  *
56  * {@link ASurfaceTexture} can be obtained from an android.graphics.SurfaceTexture object using
57  * ASurfaceTexture_fromSurfaceTexture().
58  */
59 
60 /**
61  * Release the reference to the native ASurfaceTexture acquired with
62  * ASurfaceTexture_fromSurfaceTexture().
63  * Failing to do so will result in leaked memory and graphic resources.
64  * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
65  */
66 void ASurfaceTexture_release (ASurfaceTexture* st);
67 
68 /**
69  * Returns a reference to an ANativeWindow (i.e. the Producer) for this SurfaceTexture.
70  * This is equivalent to Java's: Surface sur = new Surface(surfaceTexture);
71  *
72  * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
73  * @return A reference to an ANativeWindow. This reference MUST BE released when no longer needed
74  * using ANativeWindow_release(). Failing to do so will result in leaked resources. nullptr is
75  * returned if \p st is null or if it's not an instance of android.graphics.SurfaceTexture
76  */
77 ANativeWindow* ASurfaceTexture_acquireANativeWindow (ASurfaceTexture* st);
78 
79 /**
80  * Attach the SurfaceTexture to the OpenGL ES context that is current on the calling thread.  A
81  * new OpenGL ES texture object is created and populated with the SurfaceTexture image frame
82  * that was current at the time of the last call to {@link #detachFromGLContext}.  This new
83  * texture is bound to the GL_TEXTURE_EXTERNAL_OES texture target.
84  *
85  * This can be used to access the SurfaceTexture image contents from multiple OpenGL ES
86  * contexts.  Note, however, that the image contents are only accessible from one OpenGL ES
87  * context at a time.
88  *
89  * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
90  * \param texName The name of the OpenGL ES texture that will be created.  This texture name
91  * must be unusued in the OpenGL ES context that is current on the calling thread.
92  * \return 0 on success, negative posix error code otherwise (see <errno.h>)
93  */
94 int ASurfaceTexture_attachToGLContext (ASurfaceTexture* st, uint texName);
95 
96 /**
97  * Detach the SurfaceTexture from the OpenGL ES context that owns the OpenGL ES texture object.
98  * This call must be made with the OpenGL ES context current on the calling thread.  The OpenGL
99  * ES texture object will be deleted as a result of this call.  After calling this method all
100  * calls to {@link #updateTexImage} will fail until a successful call to {@link #attachToGLContext}
101  * is made.
102  *
103  * This can be used to access the SurfaceTexture image contents from multiple OpenGL ES
104  * contexts.  Note, however, that the image contents are only accessible from one OpenGL ES
105  * context at a time.
106  *
107  * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
108  * \return 0 on success, negative posix error code otherwise (see <errno.h>)
109  */
110 int ASurfaceTexture_detachFromGLContext (ASurfaceTexture* st);
111 
112 /**
113  * Update the texture image to the most recent frame from the image stream.  This may only be
114  * called while the OpenGL ES context that owns the texture is current on the calling thread.
115  * It will implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target.
116  *
117  * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
118  * \return 0 on success, negative posix error code otherwise (see <errno.h>)
119  */
120 int ASurfaceTexture_updateTexImage (ASurfaceTexture* st);
121 
122 /**
123  * Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by
124  * the most recent call to updateTexImage.
125  *
126  * This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s
127  * and t in the inclusive range [0, 1] to the texture coordinate that should be used to sample
128  * that location from the texture.  Sampling the texture outside of the range of this transform
129  * is undefined.
130  *
131  * The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via
132  * the glLoadMatrixf or glUniformMatrix4fv functions.
133  *
134  * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
135  * \param mtx the array into which the 4x4 matrix will be stored.  The array must have exactly
136  *     16 elements.
137  */
138 void ASurfaceTexture_getTransformMatrix (ASurfaceTexture* st, ref float[16] mtx);
139 
140 /**
141  * Retrieve the timestamp associated with the texture image set by the most recent call to
142  * updateTexImage.
143  *
144  * This timestamp is in nanoseconds, and is normally monotonically increasing. The timestamp
145  * should be unaffected by time-of-day adjustments, and for a camera should be strictly
146  * monotonic but for a MediaPlayer may be reset when the position is set.  The
147  * specific meaning and zero point of the timestamp depends on the source providing images to
148  * the SurfaceTexture. Unless otherwise specified by the image source, timestamps cannot
149  * generally be compared across SurfaceTexture instances, or across multiple program
150  * invocations. It is mostly useful for determining time offsets between subsequent frames.
151  *
152  * For EGL/Vulkan producers, this timestamp is the desired present time set with the
153  * EGL_ANDROID_presentation_time or VK_GOOGLE_display_timing extensions
154  *
155  * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
156  */
157 long ASurfaceTexture_getTimestamp (ASurfaceTexture* st);
158 
159 /* __ANDROID_API__ >= 28 */
160 
161 /* ANDROID_NATIVE_SURFACE_TEXTURE_H */